docs(onboarding): add 6.4.b real source-PR trigger (fixes #328) by serenakeyitan · Pull Request #329 · agent-team-foundation/first-tree

serenakeyitan · 2026-04-23T20:56:54Z

Summary

Closes #328.

The README's end-to-end pitch promises "source PR → tree issue → breeze pickup → draft-node PR." Step 6.4 of the onboarding narrative already demonstrated the tree side (manual gardener sync), but never scripted the actual automatic chain from a source-repo PR. Cold-start E2E on #327 confirmed a fresh agent would have to invent that leg.

Splits 6.4 into:

6.4.a — existing manual gardener sync trigger (fast credential check)
6.4.b — scripts the real source-PR chain: open a trivial PR, breeze watch / status for pickup, confirm gardener verdict, clean up

Verified against real CLI surfaces

first-tree breeze watch is the live TUI (per src/products/breeze/cli.ts:36,88)
first-tree breeze status is one-shot (per cli.ts:113)
first-tree breeze doctor reports interval + auth state (per cli.ts:121)
Not using breeze status --watch (does not exist)

Test plan

pnpm typecheck — clean
pnpm test — 1192 passing, 51 skipped, no regressions
pnpm build && node dist/cli.js tree help onboarding — narrative renders the new 6.4.b section from the bundled import

Step 6.4 already demonstrated the tree side of the chain via manual gardener sync, but never stitched in the source-PR leg the README CTA promises ("source PR → tree issue → breeze pickup → draft-node PR"). Cold-start E2E on #327 confirmed the gap: a fresh agent following tree help onboarding has to invent the final leg. Split 6.4 into two labeled sub-steps: - 6.4.a (manual trigger, ~1 min) — existing gardener sync invocation, keeps the fast credential check path. - 6.4.b (real source-PR trigger, ~5 min, optional) — scripts the actual automatic chain: open a trivial source-repo PR, watch breeze pick it up via `breeze watch` / `breeze status`, confirm gardener posted a verdict, clean up. Verified command surfaces against src/products/breeze/cli.ts: - `breeze watch` is the live TUI (not `status --watch`) - `breeze status` is one-shot - `breeze doctor` reports interval + auth state Closes #328.

yuezengwu

Two doc details in the new 6.4.b flow are still out of sync with the current CLI/runtime contract, so I’m requesting changes before approval.

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.

yuezengwu · 2026-04-23T21:02:20Z

+
+   ```bash
+   git -C <source-repo-checkout> checkout -b first-tree-smoke/drift-demo
+   echo "# drift demo $(date -u +%FT%TZ)" >> README.md


This command block mixes git -C <source-repo-checkout> with a plain echo >> README.md, so a reader who copy-pastes it from outside the source checkout will modify the current working directory instead of the smoke-test repo. That leaves the new branch unchanged and makes the subsequent commit/create-PR steps fail. Please either write to <source-repo-checkout>/README.md explicitly or run the whole block from inside that checkout.

yuezengwu · 2026-04-23T21:02:20Z

+   # or: first-tree breeze status # one-shot snapshot
+   ```
+
+   Expect a `source-pr:<N>` entry within one GitHub polling cycle


I don't think we should promise a literal source-pr:<N> entry here. The current breeze task taxonomy is review_request / comment / mention / assigned_*, and the watch/status surfaces group by status/repo/title rather than exposing a source-pr identifier. This should probably tell the reader to look for the new source PR notification in breeze watch / breeze status without naming a UI token the implementation doesn't currently emit.

yuezengwu · 2026-04-23T21:02:20Z

+   draft-node PR will appear on the tree repo; reviewing it is Scenario
+   G in the gardener skill.
+
+Report each observed step. If breeze never picks up the PR, the two


This troubleshooting note conflicts with the current routing contract. Breeze polls /notifications?participating=true, so for the PR author this notification is driven by direct participation; a missing repo watch subscription should not be the primary explanation for “breeze never picked up my PR”. I'd steer this toward the actual gates here: gh auth status, the --allow-repo scope, and whether the source PR notification appeared at all.

Three issues flagged, all real: 1. Mixed `git -C <checkout>` with a bare `echo >> README.md` that would hit cwd instead of the smoke repo. Rewrote the block to `cd <checkout>` once and keep every subsequent command plain. 2. Promised a literal `source-pr:<N>` entry that the implementation does not emit. Breeze's real task-kind taxonomy (from src/products/breeze/engine/runtime/task-kind.ts) is `review_request` / `comment` / `mention` / `assigned_issue` / `assigned_pull_request` / `discussion` / `other`. Narrative now says "a row for the new PR shows up" and names the real taxonomy as informational. 3. Troubleshooting blamed "source-repo watch subscription missing" as the primary cause for silent pickup. Breeze polls `/notifications?participating=true`, and a PR author gets the notification via participation — not via repo watch. Rewrote the troubleshooting block to walk the real gates in order: (a) does `gh api /notifications` show it, (b) is the source repo in the breeze `--allow-repo` scope, (c) `breeze doctor` for runtime errors.

serenakeyitan · 2026-04-23T21:06:44Z

Thanks — all three are real issues, addressed in the last commit:

cwd bug in the smoke commands: rewrote as a single cd <source-repo-checkout> at the top with plain git/echo commands below it, so nothing touches the wrong directory.
Invented source-pr:<N> token: dropped. Verified the real taxonomy in src/products/breeze/engine/runtime/task-kind.ts — review_request / comment / mention / assigned_issue / assigned_pull_request / discussion / other. The narrative now says "a row for the new PR shows up" and names the real taxonomy as informational, noting that self-authored PRs arrive via participation (not as review requests).
Wrong primary gate for silent pickup: rewrote the troubleshooting block. Gates in order: (a) gh api /notifications actually shows the PR (auth context sanity), (b) source repo is in the breeze --allow-repo scope, (c) breeze doctor for runtime errors. Explicitly calls out that source-repo watch subscription is not the gate for PR authors because participation alone triggers it.

yuezengwu

Thanks for the follow-up. All three points check out against the code:

cwd fix. Single cd <source-repo-checkout> at the top of the block, all subsequent git/echo/gh commands are plain — no more split cwd risk.
Task-kind taxonomy. Matches src/products/breeze/engine/runtime/task-kind.ts (review_request / mention / comment / assigned_issue / assigned_pull_request / discussion / other). Calling out that self-authored PRs arrive via participation rather than review-request is the right nuance.
Troubleshooting order. The three gates (gh notifications visibility → --allow-repo scope → breeze doctor) match reality. breeze status does surface allowed repos (per engine/commands/status.ts:69), so pointing readers there is accurate.

LGTM.

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.

## Summary Docs-only patch release so npm users get the updated onboarding narrative bundled into `first-tree tree help onboarding`. Unreleased since v0.2.14: - #325 — make end-to-end onboarding prompt source/tree-agnostic - #326 — default to breeze-first setup - #327 — fix onboarding path bootstrap chicken-and-egg - #329 — add 6.4.b real source-PR trigger ## Test plan - [x] `pnpm release:check` green locally (version:check, validate:skill, typecheck, test, build, test:dist, test:release)

yuezengwu added the breeze:wip breeze is actively working on it label Apr 23, 2026

yuezengwu requested changes Apr 23, 2026

View reviewed changes

yuezengwu added breeze:done breeze has finished handling it and removed breeze:wip breeze is actively working on it labels Apr 23, 2026

yuezengwu added breeze:wip breeze is actively working on it and removed breeze:done breeze has finished handling it labels Apr 23, 2026

yuezengwu approved these changes Apr 23, 2026

View reviewed changes

yuezengwu added breeze:done breeze has finished handling it and removed breeze:wip breeze is actively working on it labels Apr 23, 2026

serenakeyitan merged commit 6f952de into main Apr 23, 2026
1 of 2 checks passed

serenakeyitan deleted the docs/onboarding-drift-demo-328 branch April 23, 2026 21:09

serenakeyitan mentioned this pull request Apr 23, 2026

chore(release): 0.2.15 #330

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(onboarding): add 6.4.b real source-PR trigger (fixes #328)#329

docs(onboarding): add 6.4.b real source-PR trigger (fixes #328)#329
serenakeyitan merged 2 commits intomainfrom
docs/onboarding-drift-demo-328

serenakeyitan commented Apr 23, 2026

Uh oh!

yuezengwu left a comment

Uh oh!

yuezengwu Apr 23, 2026

Uh oh!

yuezengwu Apr 23, 2026

Uh oh!

yuezengwu Apr 23, 2026

Uh oh!

serenakeyitan commented Apr 23, 2026

Uh oh!

yuezengwu left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

serenakeyitan commented Apr 23, 2026

Summary

Verified against real CLI surfaces

Test plan

Uh oh!

yuezengwu left a comment

Choose a reason for hiding this comment

Uh oh!

yuezengwu Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

yuezengwu Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

yuezengwu Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

serenakeyitan commented Apr 23, 2026

Uh oh!

yuezengwu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants